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Preface 


This book is designed to help you diagnose program failures in the Direct Access 
Device Space Management (DADSM) component. Before using this publication, 
you should have analyzed the program failure by following the diagnostic 
procedures in MVS/Extended Architecture DADSM and Common VTOC Access 
Facility Diagnosis Guide, LY26-3960. 

If after following these procedures no correction is found and if you must continue 
working on the problem, use this book to help you communicate with an IBM 
program specialist. The program specialist will further isolate the failure. 


Organization 


This publication has eight parts: 

• “Introduction” includes an overview of DADSM, a summary of its major 
functions, and a figure describing how these functions work together. 

• “Program Design and Organization” describes each DADSM function and 
subfunction, the interface to the controlling module, the system and DADSM 
data areas used, and a flowchart for each function or subfunction. These 
flowcharts contain brief module descriptions and the logic that determines the 
flow of control among DADSM routines. 

• “Module Directory” contains a cross-reference table to the DADSM object 
modules. 

• “Data Areas” briefly describes each significant DADSM data area and control 
block. 

• “Data Area Linkage” shows how the data areas are linked together. 

• Appendix A, “Data Area Layouts,” lists the offset, length, name, and field 
description of each significant data area. 

• Appendix B, “DADSM Return Codes,” lists by function each DADSM return 
code and explains what these return codes mean. 

• “Abbreviations” defines the abbreviations used in this book. 
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Prerequisite Knowledge 

To use this book efficiently, you need to have already made a preliminary analysis 
of the program failure. The information you obtained from your analysis is the 
prerequisite knowledge for using this book. 


Required Publications 

You should be familiar with the information presented in MVS/Extended 
Architecture DADSM and Common VTOC Access Facility Diagnosis Guide, 
LY26-3960. This book explains how to analyze program failure. 


Related Publications 

Within the text, references are made to the publications listed in the table below: 


Short Title 

Publication Title 

Order 

Number 

DADSM and CVAF 
Diagnosis Guide 

MVS/Extended Architecture 
DADSM and Common VTOC 
Access Facility Diagnosis Guide 

LY26-3960 

Data Facility Product: 
Customization 

MVS/Extended Architecture 

Data Facility Product Version 2: 
Customization 

GC26-4267 

DFDSS: Diagnosis 

Guide 

Data Facility Data Set Services: 
Diagnosis Guide 

SC26-3951 

JES2 Data Areas 

MVS /Extended Architecture 

Data Areas (MVS/JES2) 

LYB8-1191 

JES3 Data Areas 

MVS/Extended Architecture 

Data Areas (MVS/JES3) 

LYB8-1195 

Open/Close/EOV 

Logic 

MVS/Extended Architecture 
Open/Close/EOV Logic 

LY26-3966 

System Messages 

MVS/Extended Architecture 
Message Library: System 
Messages, Volumes 1 and 2 

GC28-1376 

GC28-1377 

VSAM Logic 

MVS/Extended Architecture 

VSAM Logic 

LY26-3970 
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Summary of Changes 


I Release 3.0, June 1987 


| New Progr amming Support 

| The majority of DADSM code has been moved above 16Mb virtual, giving 

I approximately 100K bytes of virtual storage constraint relief. Linkage assist 

| modules have been added and load modules have been redefined. 

I DADSM functions continue to be supported for 24-bit addressing mode callers 

| without change. 

| Functions other than PROTECT now support 31-bit addressing mode callers and 

| their parameters above 16Mb virtual. 

| A new LSPACE macro has been added. This macro may be used to: 

| • Define a parameter list for the SVC 78 (LSPACE) function which will support 

I 24-bit and 31-bit addressing mode callers. 

I • Request the existing LSPACE return message area. 

| • Request the existing SMF functions. 

| • Request a new data return area format with additional volume-oriented 

| information. 

| • Request the return of the format-4 DSCB’s data. 

| LSPACE diagnostic information has been improved. 

| The PARTREL macro has been modified to accept requests for ERASE (YES, 

| NO, or TEST) and TIOT (ENQ or NOENQ). 
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Release 1.0, April 1985 


New Programming Support 

The following features have been added to the DADSM component: 

« A new PARTREL macro which will enable authorized users to effect a partial 
release of the space allocated to a data set without an associated 
OPEN/CLOSE. 

* A modified REALLOC macro which will: 

- Support all functions of the previous REALLOC macro. 

— Enable authorized users to cause the reallocation of a data set with as 
many as 16 absolute extents, and an optional Format 2 (ISAM) DSCB, on 
a given volume with an indexed VTOC. 

* SCRATCH will erase tracks for deleted data sets when requested by its caller 
or when a RACF-defined data set has the ERASE attribute. 

* Partial Release will erase tracks for space being released when the data set is 
RACF defined and has the ERASE attribute. 

Version 2 Publications 


The Preface includes the new order numbers for Version 2. A new REALLOC 
macro to enable users to reallocate data sets through the DADSM partial DSCB 
allocate function 
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Introduction 


This publication provides a summary of the major functions of the direct access 
device space management (DADSM) component, and a brief overview of its logic 
and organization. It introduces the descriptions of program activities that are 
found in the module prologs and as comments in the code, but it is not intended to 
replace those descriptions. In addition, this book is not intended to show you how 
to modify or repair the program logic. It will, however, give you an adequate basis 
for communicating with an IBM program specialist about possible program failures. 

If you do have a program failure, do NOT start your diagnosis of the problem by 
referring to this manual. You should begin diagnosis by following the instructions 
and procedures set forth in DADSM and CVAF Diagnosis Guide. 


Overview of DADSM 

The DADSM functions control allocation of space on direct access volumes 
through the volume table of contents (VTOC) of that volume. The VTOC is a 
data set consisting of a collection of data set control blocks (DSCBs) that describe 
the contents of a direct access storage device volume. There are seven types of 
DSCBs; each has a different purpose and is assigned a different name and format 
number. The VTOC and, optionally, the VTOC index, are built during volume 
initialization by Device Support Facilities, program number S65S-2S7. The VTOC 
and the VTOC index each reside in a single extent (that is, a contiguous data set). 
The VTOC’s address is located in the VOLVTOC field of the IBM-defined volume 
label. 

DADSM will use the common VTOC access facility (CVAF) macros to determine 
the VTOC format and to access an indexed VTOC. DADSM uses CVAF as well 
as channel programs to access a nonindexed VTOC. 

The VTOC may have a VTOC index. The VTOC index contains space maps that 
replace the format-5 DSCBs of the nonindexed VTOC and manage the VTOC and 
VTOC index space. The VTOC index contains an index of all the format-1 and 
format-4 DSCBs. 

The different types of DSCBs are: 

• Free DSCB: format-0 

• Identifier DSCB: format-1 

• Index DSCB (ISAM only): format-2 
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• Extension DSCB: format-3 

• VTOC DSCB: format-4 

• Free space DSCB: format-5 

• Shared extent DSCB: format-6 

Each DSCB in the VTOC corresponds either to a data set or data space currently 
residing on the volume, or to contiguous, unassigned tracks on the volume. DSCBs 
are the data set labels, which describe the characteristics of the data set or data 
spaces as well as the tracks on which the data sets reside. DSCBs for unassigned 
tracks indicate the location of unassigned, contiguous tracks. 

The functions performed by DADSM for controlling space allocation are: 

• Allocating space for new VIO data sets, non-ISAM data sets, and VSAM data 
spaces (NONIALL, subfunction of the ALLOC function) 

• Allocating space for new ISAM data sets (IALL, subfunction of the ALLOC 
function) 

• Allocating additional space for non-ISAM data sets and VSAM data spaces 
(EXTND function) 

• Rebuilding the format-5 chain and updating the format-4 
DSCB (CONV function) 

• Deleting a data set or VSAM data space (SCRTCH function) 

• Freeing allocated but unused space (PRLSE function) 

• Renaming data sets (RNAME function) 

• Reading DSCBs (OBTN function) 

• Calculating available space on a direct access volume (LSPACE function) 

• Maintaining the system password data set (PRTCT function) 

• Recovering from interrupted indexed VTOC processing (VRF function) 

Allocating and Releasing Space on Direct Access Volumes 

The DADSM functions that allocate (ALLOC and EXTND) and release space 
(SCRTCH and PRLSE) also add, delete, and modify DSCBs of the VTOC. To 
make space available to a new data set or to increase the space allocated to a data 
set, the format-5 DSCBs or VTOC indexed space maps are searched for available 
space. The space is allocated to the data set by writing the description of the 
space, called an extent, to the data set’s DSCB and deleting the extent from the 
space available for allocation. To release space allocated to a data set, the allocate 
operation is reversed: The released extent is deleted from the data set’s DSCB and 
added to the existing space available for allocation. 
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Components of the operating system use the DADSM functions to allocate and 
release space in response to data definition (DD) statements. For example, the job 
management (scheduler) routines call the ALLOC function to obtain space for a 
new data set. 

VTOC-Related Service Functions 

RNAME, OBTN, LSPACE, and PRTCT functions are used to read and change 
control information on the VTOC; they neither allocate nor release space. System 
macro instructions can be used to invoke these functions. 

Volume Table of Contents Integrity 

In an operating system with only one processor, two or more tasks may attempt to 
access the same VTOC simultaneously for the purpose of reading or updating (that 
is, adding, deleting, or modifying DSCBs) that VTOC. If more than one processor 
has access to the same device or devices, they may attempt to access the VTOC 
simultaneously. 

To be sure that a VTOC is not changed while the DADSM functions are in 
process, the DADSM functions issue RESERVE, ENQ, and DEQ macro 
instructions. These macro instructions provide or release exclusive control of the 
VTOC for the task issuing the macro instruction. The RESERVE macro 
instruction is needed for systems in which two or more processors are processing 
concurrently, using the same data sets. These macro instructions provide exclusive 
control of the VTOC for the task issuing the macro instruction. Depending on the 
macro instruction, the “set-must-complete” option or the “release-must-complete” 
option may be specified in an operand of the macro instruction. The ALLOC, 
EXTND, SCRTCH, RNAME, PRLSE, LSPACE, and PRTCT functions of 
DADSM issue these macro instructions. Of these routines, only ALLOC, 

SCRTCH and PRLSE, use SMC=STEP in the ENQ and RESERVE macros, and 
RMC=STEP in the DEQ macro. The EXTND function links to the status routine 
(rather than issuing the ENQ macro) to obtain “step-must-complete” status, if the 
task that called EXTND has not already done so. 

The integrated catalog facility/virtual storage access method (integrated catalog 
facility/VSAM) catalog management routines modify the DS4AMCAT and 
DS4AMT1M fields of the VTOC (format-4) DSCB. These routines also issue the 
RESERVE, ENQ, and DEQ macro instructions to maintain exclusive control while 
making modifications. 

Note: When operating in an environment in which direct access storage devices 
are not shared among systems, the RESERVE macro instruction defaults to (acts 
as) an ENQ macro instruction. 

Interrupted VTOC-Update Functions 

If a system fails or a permanent I/O error occurs during allocation of space or 
during a routine that updates the VTOC, the VTOC will probably be in error. To 
make sure the error is recorded, the DADSM functions use the DADSM 
interrupt-recording facility (DIRF) when a nonindexed VTOC is being accessed. If 
the VTOC is an indexed VTOC, the VTOC recording facility (VRF) is used to 
record and recover from interrupted VTOC-update functions. 
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DADSM Interrupt Recording Facility (DIRF): DIRF processing is applicable only to 
nonindexed VTOCs and involves turning on a bit in the VTOC at entry to the 
DADSM function, and, if no I/O errors occur during DADSM processing, turning 
it off again at exit from that function. 

This bit is called the DIRF bit and is bit 5 of the DS4VTOCI field of the format-4 
DSCB. The SCRTCH and PRLSE functions also turn on the DIRF bit if they 
encounter overlapping extents in a format-5 DSCB. 

When a volume has been transported from a Disk Operating System (DOS), it will 
have the DOS bit on (bit 0 of the DS4VTOCI field of the format-4 DSCB). 

The next time an attempt is made to allocate space on a volume that has either the 
DOS bit or the DIRF bit set, the VTOC conversion routine (CONV) is invoked by 
the ALLOC or EXTND functions, whichever is attempting to allocate more space 
on the volume. The CONV function builds new format-5 DSCBs to represent the 
available space on the volume, updates the format-4 DSCB, and returns to ALLOC 
or EXTND to continue the allocation. 

VTOC Recording Facility (VRF): VRF processing is applicable only to indexed 
VTOCs and records more functionally related data than DIRF. The additional 
data allows VRF processing to correct a specific problem rather than rebuilding the 
VTOC each time DADSM is interrupted. VRF is invoked by the ALLOC, 
SCRTCH, EXTND, PRLSE, and RNAME functions. 


I Installation Exits 


The ALLOC, EXTND, SCRTCH, PRLSE, and RNAME functions call pre- and 
postprocessing installation exits. These exits, IGGPREOO and IGGPOSTO, allow 
your installation to control DASD space or reject requests based on installation 
criteria. 

For more information on installation exits, see Data Facility Product: Customization. 


Linkage Assist Routines 


DADSM provides seven linkage assist routines. IGG0553A is the linkage assist 
routine for the EXTND function. IGG0553A allows callers in 24-bit addressing 
mode to branch to the EXTND module, IGG05530. Callers in 31-bit addressing 
mode may call IGG05530 directly. 

IGGPEXIT is the linkage assist routine for the installation exit modules 
IGGPREOO and IGGPOSTO. IGGPEXIT is used to branch to an installation exit 
module when that module is in 24-bit addressing mode. If the module is in 
31-addressing mode, control passes directly to the installation exit. 

The remaining five linkage assist routines are used with installation replaceable 
modules in the SCRTCH and RNAME functions. These linkage assist routines are 
always called, regardless of whether the caller is in 24- or 31-bit addressing. 
IGGDASOO, IGC0002I, and IGG029DN are used with the SCRTCH function. 
IGGDAROO and IGC00030 are used with the RNAME function. 
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DADSM Recovery Routines 

To avert a complete system failure when an abnormal termination condition arises 
in DADSM processing, the DADSM functions include a recovery function. This 
function is given control by the recovery/termination manager (R/TM) when an 
abnormal termination condition is encountered in a DADSM routine. The same 
recovery routine is given control when an open, close, or EOV routine encounters 
an abnormal termination condition; the DADSM recovery function is therefore 
documented in Open,/Close/EOV Logic. 

During the initialization of each DADSM function, the address of the recovery 
routine is established when virtual storage is obtained by the DADSM function. 

The O/C/EOV-DADSM recovery routine load module name is DFGORROA. Its 
address is established for a DADSM routine when the IECRES GET macro is 
issued for a work area. The functions of the IECRES macro, the expansion of 
which results in a branch to the O/C/EOV-DADSM service routine, IFG019RA, 
are also documented in Open/Close/EOV Logic. 

The DADSM recovery routine saves diagnostic information in the SYS1.LOGREC, 
SYS1.DUMP, and GTF data sets, and then releases any resources obtained by the 
DADSM function before it failed. 


Functions of DADSM 

Figure 1 on page 9 summarizes the major functions in DADSM. In this section, 
each of these functions is described in terms of its external processing environment. 
For each function, the following information is provided: 

• Description: a brief description of the function 

• Results: the processing results produced by the function 

• Calling components: where applicable, the system components that can 
transmit requests to the function 

In the following discussion, note that each function is identified by a function 
name. This name is the same as the keyword name used to identify the function in 
DADSM and CVAF Diagnosis Guide. All functions return to the caller when the 
requests are fulfilled. 

ALLOC Function 

Description Processes requests to allocate space on a direct access 

storage device. The ALLOC function is invoked by an 
SVC 32. 

Results Updated VTOC index and/or VTOC reflecting the new 

contents and space available on the volume. Return 
code in register 15. 
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EXTND Function 


I 


SCRTCH Function 


PRLSE Function 


Calling Components Scheduler, utilities, integrated catalog facility and 

VSAM catalog management, REALLOC macro, and 
any other caller of SVC 32. 


Description Allocates additional space (extents) to sequential data 

sets or VSAM data spaces. EXTND is invoked when a 
data set requires more space than is currently allocated. 
EXTND can also process VSAM requests that do not 
include a data extent block (DEB) parameter. 

Results Updated VTOC index and/or VTOC reflecting the new 

contents and space available on the volume. The return 
code is in register 13. 

Calling Components EOV, integrated catalog facility and VSAM catalog 

management, OS catalog management. 


Description Deletes data sets and VSAM data spaces. Optionally, 

erases DASD tracks before releasing space. The 
SCRTCH function is invoked by the SCRATCH macro 
instruction (SVC 29). 

Results Updated VTOC index and/or VTOC. The return code 

is in register IS. Scratch status code is in volume list. If 
erase processing is performed, residual user data is made 
unreadable. 

Calling Components Integrated catalog facility and VSAM catalog 

management, MSS, scheduler, utilities, or problem 
program. 


Description Releases unused space, and extents, allocated to a 

sequential or partitioned data set. Optionally, erases 
DASD tracks before releasing space. The PRLSE 
function may be invoked by a close issued for a data set 
for which a release has been specified in the DD card, or 
a restart from a checkpoint where a data set has been 
extended after the checkpoint, or an authorized user of 
the PARTREL macro. 

Results Updated VTOC index and/or VTOC. The return code 

for a close or checkpoint/restart caller is in register 1. 
The return code for a PARTREL caller is in register 15. 
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RNAME Function 

Description 

Finds the DSCB for a specified data set or VSAM data 
space and changes its name. The RNAME function is 
invoked by the RENAME macro instruction (SVC 30). 


Results 

The updated VTOC index and/or VTOC with the new 
data set or VSAM data space name (after verifying that 
the requested name does not duplicate one already on 
the volume). The rename status code is in volume list. 
The return code is in register IS. 


Calling Components 

HSM, utilities, or problem program. 

OBTN Function 

Description 

Reads a specified DSCB from the VTOC of a specified 
volume into the caller’s work area; for suballocated 
VSAM data sets, obtains equivalent information from 
the appropriate VSAM catalog. The OBTN function is 
invoked by the OBTAIN macro instruction (SVC 27). 


Results 

The requested information is put in the caller’s work 
area. The return code is in register IS. 


Calling Components 

System components, problem program, and utilities. 

LSPACE Function 

Description 

Calculates the amount of free space on a given direct 
access volume. When called with a parameter list, 
LSPACE can calculate the fragmentation index, and 
report on the number of format-0 DSCBs and free 

VIRs. LSPACE returns this information in a data 
(rather than a message) format. The LSPACE function 
is invoked by an SVC 78. 


Results 

A type-19 record is written to the SMF data set, if SMF 
is requested and is active on the system. If the 
MONITOR SPACE command was issued, space 
information is moved to the message area provided by 
the caller. The message or parameter list address is in 
register 1. The reason code is in register 0; the return 
code is in register IS. 

1 

1 

Calling Components 

LSPACE macro, MSS, O/C/EOV, scheduler, SMF, 
problem program, and utilities. 
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PRTCT Function 

Description Maintains the system password data set, which controls 

access to data sets and associated control information. 
The PRTCT function is invoked by the PROTECT 
macro instruction (SVC 98). 

Results For add, replace, and delete operations, the password 

data set is updated. For list operations, the caller’s 
80-byte buffer contains the requested record. The 
return code is in register IS. 

Calling Components Utilities, problem program. 

VRF Function 

Description Accesses recovery data and corrects the VTOC and 

VTOC index to an executable state after an interrupted 
VTOC update: indexed VTOC only. The condition that 
causes invocation of the VRF function is any function 
that detects active VRF data in the VTOC index. 

Results The recovery of interrupted update processing or the 

VTOC index is disabled. The return code is in register 
15 . 

Calling Components DADSM, DFDSS. 
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Figure 1. How Functions of DADSM Work Together 
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Program Design and Organization 


In this section, the following information is provided for each function of DADSM: 

• Description: a brief description of the function 

• Interface to Controlling Module: the interface to the module that controls or 
oversees processing within the function 

• System and DADSM Data Areas Used: the names of the data areas used by 
the function (or subfunction) 

• Program Organization: charts showing the module-to-module flow 

ALLOC Function 


The allocate routines find unused space on direct access storage volumes and make 
that space available for new data sets. They receive control through an SVC 32. 
These routines create a format-1 data set control block (DSCB) for each new data 
set, and, in the format-1 DSCB, write descriptions of the direct access storage areas 
(these description are called extents). Available extents are obtained by searching 
the format-5 DSCBs on the VTOC (for a nonindexed VTOC) or the volume pack 
space map (VPSM) of the VTOC index. The allocate routines are divided into 
four subfunctions and are described below. 


INIT Subfunction 


Description 

The INIT subfunction verifies that space requests are properly made, performs 
space allocation for VIO data sets by building the virtual DSCB (VDSCB), 
prepares for non-VIO data set allocation, takes the preprocessing exit, and 
determines whether there is an indexed VTOC on the volume. If a REALLOC 
ALLOC=ABS request is made for a volume without indexed VTOC support, the 
request will fail. 

Interface to Controlling Module 

If register 1 has the high—order bit on, the complement of register 1 is the address 
of the REALLOC caller’s parameter list. 

For callers other than REALLOC, register 0 points to the job file control block 
(JFCB); however, if register 0 has the high-order bit on, register 0 points to a 
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partial DSCB. Register 1 points to the unit control block (UCB) for the device on 
which the data set is to be located or, if a VIO data set is being allocated, register 1 
points to a device code. Register 2 points to a variable-length list of DSAB 
addresses if an ISAM data set is being allocated. 

System Data Areas Used 

Allocate work area 

DADSM Data Areas Used 

Buffer list 

CVAF extent table 

CVAF parameter list 

DADSM extent table 

DADSM preprocessing and postprocessing installation exit parameter list 
Partial data set control block (PDSCB). 

Data set control blocks (DSCB) 

REALLOC parameter list 

System Authorization Facility (SAF) work area and parameter list 
Transfer control table 
VTOC recording facility data 
WTG table 
Program Organization 
See Figure 2 on page 13. 
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Figure 2. Allocation Initialization 
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NON1ALL Subfunction 


Description 

The NONIALL subfunction converts the space requested for a data set or VSAM 

data space to the equivalent number of tracks, determines the type of allocation 

request, allocates space, and (for an indexed VTOC) adds a new entry to the index. 

NONIALL receives control from the INIT subfunction and allocates space for 

non-ISAM data sets: 

• Calls SAF to verify access authority via RACF generic or discrete profile. 
Defines a discrete profile if the caller has requested it. 

• If user labels are requested, a user-label track is allocated from the VPSM for 
an indexed VTOC or format-5 DSCBs for a nonindexed VTOC. 

• Absolute-track allocation requests for nonindexed VTOCs locate the extent 
containing the specified track in the format-5 DSCB for a nonindexed VTOC 
or the VPSM for an indexed VTOC. 

• For cylinder or track allocation requests, the extents required to fill the request 
are located through the format-5 DSCB for a nonindexed VTOC or the VPSM 
for an indexed VTOC. 

• When space is needed on a volume, the VTOC is checked for enough 
contiguous tracks; the request is Med, using as many as five noncontiguous 
groups of free tracks. The appropriate DSCBs and VTOC index records are 
modified to reflect the assignment of the tracks. 

• The data set name is added to the index for an indexed VTOC. 

• Format-1 and format-3 DSCBs are built, if required. 

• The VTOC index space maps are updated. 

• The format-4 and format-5 DSCBs are updated for a nonindexed VTOC. 

• If a REALLOC ALLOC=MOV request is made (high-order bit is on in 
register 1 upon entry to the INIT subfunction and the parameter list indicates 
ALLOC=MOV) space will be filled in as many as 16 noncontiguous groups of 
free, tracks for any data set not cataloged in an integrated catalog facility 
catalog, and as many as 123 noncontiguous groups of free tracks for any 
VSAM data set cataloged in an integrated catalog facility catalog. Optionally, 
the groups will be a minimum number of tracks as specified in the parameter 
list passed from the caller. 
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• If a REALLOC ALLOC=ABS request is made (high-order bit is on in register 
1 upon entry to the INIT subfunction and the parameter list indicates 
ALLOC sABS) the specified volume’s indexed VTOC support will be used in 
allocating the absolute extents requested by the caller’s format 1, and 
(optional) format-3 DSCB parameters. The VTOC and VTOC index records 
will be updated using the caller’s format 1, optional format 2, and optional 
format-3 DSCB specifications. 

Interface to Controlling Module 

Register 11 points to the job file control block (JFCB); however, if register 11 has 
its high-order bit on, register 11 points to the partial DSCB (full format-1 DSCB 
for REALLOC ALLOC=ABS). Register 13 points to the allocate work area. 

System Data Areas Used 

Allocate work area 

DADSM Data Areas Used 

Buffer list 

CVAF extent table 

CVAF parameter list 

DADSM extent table 

DADSM preprocessing and postprocessing installation exit parameter list 
Partial data set control block (PDSCB). 

Data set control blocks (DSCB) 

REALLOC parameter list 
SAF work area and parameter list 
Transfer control table 
VTOC recording facility data 
WTG table 
Program Organization 
See Figure 3 on page 16. 
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Figure 3. Non-ISAM Allocation 
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1ALL Subfunction 


Description 

The IALL subfunction receives control from the INIT subfunction and allocates 
space for 

• ISAM data sets. 

• Finding available space on the volume by searching the format-5 DSCBs on 
the VTOC or the VPSM (for an indexed VTOC) in the VTOC index and 
budding an extent table of the available space. 

• When space is needed on a volume, the VTOC is checked for enough 
contiguous, available tracks to satisfy the request. If there are not enough 
contiguous tracks, the request is filled, using as many as five noncontiguous 
groups of free tracks. The appropriate DSCBs and VTOC index records are 
modified to reflect the assignment of the tracks. 

• Adding a new DSN entry to the VTOC index (for an indexed VTOC). 

• Building format-1, format-2, and format-3 DSCBs. 

• Updating format-4 and format-5 DSCBs (for a nonindexed VTOC). 

• Updating the VTOC index (for an indexed VTOC). 

If an ISAM data set is to be allocated on more than one volume, multivolume data 
set initialization is performed and IALL processing begins again. IALL calls SAF 
to verify authority via RACF generic or discrete profile and adds the new volume 
to the existing discrete profile when requested by the caller. 

Interface to Controlling Module 

Register 11 points to the job file control block (JFCB). Register 13 points to the 
allocate work area. 

System Data Areas Used 

Allocate work area 

DADSM Data Areas Used 

Buffer list 

CVAF extent table 

CVAF parameter list 

DADSM extent table 

DADSM preprocessing and postprocessing installation exit parameter list 
Data set control blocks (DSCB) 
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SAF work area and parameter list 
Transfer control table 
VTOC recording facility data 
WTG table 
Program Organization 
See Figure 4 on page 19. 
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Figure 4 (Part 1 of 2). 
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CONV Subfunction (For Nonindexed VTOCs Only) 

Description 

The CONV subfunction receives control from the ALLOC INTT subfunction or the 

EXTND function if one of the following conditions is met: 

• The volume has been processed under the DOS operating system leaving the 
DOS bit (DSDOSBT in field DS4VTOCI) on in the format-4 DSCB. 

• The volume previously contained an indexed VTOC, but the VTOC index was 
disabled, leaving the DOS bit on in the format-4 DSCB. 

• A permanent I/O error or system failure during DADSM processing occurred, 
leaving the DIRF bit (DSDIRF in field DS4VTOCI) on in the format-4 DSCB. 

The procedure to reclaim and convert VTOCs involves: 

• Rebuilding the format-5 DSCBs by removing format-1 and format-3 extents 
from total volume space. 

• Writing format-5 DSCBs to the VTOC. 

• Rebuilding the format-6 DSCBs from the format-1 DSCBs. 

• Updating the format-4 DSCB. 

Interface to Controlling Module 

Register 7 points to the UCB for the volume whose VTOC is to be converted. 

Register 13 points to the allocate work area. 

System Data Areas Used 
Allocate work area 

DADSM Data Areas Used 

Data set control blocks (DSCB) 

Transfer control table 
WTG table 

Program Organization 

See Figure 5 on page 23. 
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Deactivating Automatic VTOC Reclamation 


There are situations in which you may not want to automatically convert or reclaim 
a VTOC that has the DIRF bit set in the format-4 DSCB. By applying a superzap, 
or in-storage, alteration to IGG0325Z, you can prevent the VTOC from being 
automatically reclaimed. The job control language and control statements for 
altering IGG032SZ follow: 

//STEP01 EXEC PGM=AMASPZAP 
//SYSLIB DD DSN=SYS1.LPALIB,DISP=OLD 
//SYSPRINT DD SYSOUT=A 
//SYSIN DD * 

NAME IGG0325Z IGG0325Z 
VER 0000 0700 

REP 0000 0701 

/* 


22 MVS/XA DADSM Diagnosis Reterence 


LY26-3961-1 © Copyright IBM Corp. 1980,1987 



Restricted Materials of IBM 
Licensed Materials - Property of IBM 



Figure 5. VTOC Conversion Routine (Nonindexed VTOC only) 
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EXTND Function 


Description 

The EXTND function initializes extension of data set allocation and proceeds as 
follows: 

• Calculates the last track written to the data set when an extension is to be 
made of the current volume and determines whether the secondary space 
request can be filled by the tracks following the last allocated track. 

• Searches format-5 DSCBs or the VPSM (for an indexed VTOC) for free 
extents and builds an extent table. 

• When space is needed on a volume, the VTOC is checked for enough 
contiguous, available tracks to satisfy the request. If there are not enough 
contiguous tracks, the request is filled, using as many as five noncontiguous 
groups of free tracks. The appropriate DSCBs and VTOC index records are 
modified to reflect the assignment of tracks. 

• Builds and/or updates the appropriate format-1 and format-3 DSCBs. 

• Adds the DSN to the VTOC index if the extension is to a new volume. 

• When extending onto a new volume, calls SAF to verify authority via RACF 
generic or discrete profile. In the case of a discrete profile, adds the new 
volume to the existing discrete profile. 

• Updates the appropriate format-4 and format-5 DSCBs (for a nonindexed 
VTOC only). 

• Updates the VTOC index. 

Note: Data sets with indexed sequential organization or data sets beginning with 
“SYSl.VTOaX” cannot be extended. 

EXTND can process VSAM requests that do not include a DEB parameter. 
Interface to Controlling Module 

Register 4 points to the O/C/EOV work area. Register 5 points to the data extent 
block (DEB) of the data set to be extended. Register 10 points to the UCB for the 
volume. Register 13 contains the extend code. 
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System Data Areas Used 
Extend work area 
DADSM Data Areas Used 
Buffer list 
CVAF extent table 
CVAF parameter list 
DADSM extent table 

DADSM preprocessing and postprocessing installation exit parameter list 
Data set control blocks (DSCB) 

SAF work area and parameter list 
Transfer control table 
VTOC recording facility data 
WTG table 
Program Organization 
See Figure 6 on page 26. 
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SCRTCH Function 

Description 

For each volume, the SCRTCH function does the following: 

• Determines whether a volume containing the data to be scratched is mounted 
on a unit allocated to the job. If the volume is not mounted, SCRTCH 
requests that the required volume be mounted. 

• Reads in format-4 (for nonindexed VTOCs only) and format-1 DSCBs for the 
data set to be scratched. 

• Calls SAF to verify authority via RACF generic and/or discrete profiles. A 
discrete profile will be deleted. 

• Calls SAF to determine via RACF whether data set erasure is to be performed 
when the caller of SCRTCH does not explicitly specify such action. 

• If required, makes all DASD tracks allocated to the data set unreadable before 
removing DSCBs. 

• Removes the format-1, format-2, and format-3 DSCBs for data sets being 
scratched. 

• For MSS virtual volumes, relinquishes space. 

• Deletes the data set name from the VTOC index. 

• Updates (for a nonindexed VTOC) the format-4, format-5, and (for 
split-cylinder data sets) format-6 DSCBs. 

• Updates the VPSM (for an indexed VTOC). 

Interface to Controlling Module 

Register 0 contains all zeros or points to the UCB for the device that can be used 

to mount volumes. Register 1 points to the scratch parameter list. 

System Data Areas Used 
Scratch work area 
Second scratch work area 
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DADSM Data Areas Used 

Acquire/Relinquish parameter list 
Buffer list 
CVAF extent table 
CVAF parameter list 
DADSM extent table 

DADSM preprocessing and postprocessing installation exit parameter list 
Data set control blocks (DSCB) 

SAF work area and parameter list 
Transfer control table 
VTOC recording facility data 
WTG table 
Program Organization 
See Figure 7 on page 29. 
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PRLSE Function 


Description 

The PRLSE function deletes unused space, and extents, allocated to sequential or 
partitioned data sets as follows: 

• Calls SAP to determine via RACF whether erasure is to be performed for 
released tracks when the caller of PRLSE does not explictly specify such 
action. 

• Reads in the format-4 DSCB, and processes the DIRF for a nonindexed 
VTOC, or VRF for an indexed VTOC 

• If required, invokes the DADSM track erase module (IGG029ER) to make 
released tracks unreadable 

• Updates the format-1 DSCB 

• Updates or removes the format-3 DSCB 

• Writes back the format-1 and format-3 DSCBs 

• For MSS virtual volumes, relinquishes space 

• Updates the format-4 and format-5 DSCBs (for a nonindexed VTOC) 

• Updates the VPSM (for an indexed VTOC) 

Interface to Controlling Module (IGG020P0) 

Register 1 points to the PARTREL parameter list. Register 13 points to a standard 
register save area. Register 14 provides the desired return address. 

Interface to Controlling Module (IGG020P1) 

If register 2 contains zero, entry was made from IGG020P0. Register 3 points to a 
partial data control block (DCB) which points to an area for the construction of a 
dummy DEB. Register 4 points to a partially initialized O/C/EOV work area. 
Register 10 points to the UCB of the data set whose space allocation is to be 
reduced. Register 13 points to the partial release work area (the data set name is 
passed within this area). 

For callers other than IGG020P0, register 2 points to the DCB for the data set 
whose space allocation is to be reduced. Register 4 points to the O/C/EOV work 
area. Register 7 points to the restart work area if entry is from restart. Register 10 
points to the UCB of the data set whose space allocation is to be reduced. 
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System Data Areas Used 
Partial release work area 
DADSM Data Areas Used 

Acquire/Relinquish parameter list 
Buffer list 
CVAF extent table 
CVAF parameter list 
DADSM extent table 

DADSM preprocessing and postprocessing installation exit parameter list 
Data set control blocks (DSCB) 

PARTREL parameter list 
PARTREL partial release work area 
SAF work area and parameter list 
Transfer control table 
VTOC recording facility data 
WTG table 
Program Organization 
See Figure 8 on page 33. 
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Figure 8. Partial Release 
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PRTCT Function 

Description 

The PRTCT function: 

• Reads a format-1 DSCB for the PASSWORD data set from the system volume 

• Adds, replaces, deletes, or lists entries in the system PASSWORD data set 

• Updates the format-1 DSCB 

Note: VSAM data spaces are protected using another method. See VSAM Logic. 

Interface to Controlling Module 

Register 1 points to the protect parameter list. 

System Data Areas Used 
Not applicable 
DADSM Data Areas Used 

Data set control blocks (DSCB) 

Protect work area 
Program Organization 
See Figure 9 on page 35. 
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RNAME Function 

Description 

The RNAME function: 

• Determines whether the volume is mounted on a unit allocated to the job; if 
not, RNAME requests that the required volume be mounted. 

• Calls SAF to verify authority via RACF generic or discrete profiles. Renames 
the discrete profile when one exists. 

• Deletes the old data set name from the VTOC index and adds the new data set 
name to the VTOC index (for an indexed VTOC only). 

• Updates the format-1 DSCB with the new data set or VSAM data space name. 

• Writes a type-18 SMF record, if necessary. 

• Processes additional volumes. 

Interface to Controlling Module 

Register 0 contains all zeros or points to the UCB of the device that can be used to 

mount volumes. Register 1 points to the rename parameter list 

System Data Areas Used 
Not applicable 

DADSM Data Areas Used 
Buffer list 
CVAF extent table 
CVAF parameter list 
DADSM extent table 

DADSM preprocessing and postprocessing installation exit parameter list 
Data set control blocks (DSCB) 

Rename work area 

SAF work area and parameter list 
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Second rename work area 
Transfer control table 
VTOC recording facility data 
WTG table 


Program Organization 
See Figure 10 on page 38. 
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OBTN Function 

Description 

The OBTN function: 

Reads one DSCB into the caller’s work area, which contains either: (1) the 
96-byte data portion of the format-1 DSCB (or format-4 if the data set name 
is 44 characters of X'04' of the named data set, along with its absolute track 
address (CCHHR); or (2) the 140-byte DSCB whose absolute track address is 
supplied; or (3) for VIO data sets, the virtual DSCB. 

Interface to Controlling Module 

Register 1 points to the obtain parameter list. 

System Data Areas Used 

Not applicable 

DADSM Data Areas Used 

Buffer list 

CVAF parameter list 

DADSM preprocessing and postprocessing installation exit parameter list 
Data set control blocks (DSCB) 

Obtain work area 
Transfer control table 
WTG table 
Program Organization 
See Figure 11 on page 40. 
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Figure 11. Obtain 
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LSPACE Function 


I 

l 


Description 

The LSPACE function: 

• Calculates the unallocated volume space from format-5 DSCBs (for a 
nonindexed VTOC) or the VPSM (for an indexed VTOC). 

• Optionally calculates the fragmentation index. 

• Optionally reports the number of format-0 DSCBs and free VIRs. 

• Optionally returns the format-4 DSCB. 

• If SMF information is required, the volume label is read in and a type-19 
record is constructed and written to the SMF data set. 

• If the MONITOR SPACE command is in effect, space information is placed in 
the caller’s message area. 

Interface to Controlling Module 

Register 0 points to the UCB of the device on which the volume is (or can be) 
mounted. Register 1 contains the SMF code in the high-order byte and points to 
the message area in the three low-order bytes. 

System Data Areas Used 

Not applicable 

DADSM Data Areas Used 

Buffer list 

CVAF parameter list 

DADSM preprocessing and postprocessing installation exit parameter list 
Data set control blocks (DSCB) 

LSPACE work area 
Transfer control table 
WTG table 
Program Organization 
See Figure 12 on page 42. 
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C 


START 


O/C/EOV, scheduler, 
SMF, MSS 


IGC0007H A 


Initializes LSPACE 
function 


IGC0107H f 


Error 


c 


Return to caller 


3 


Totals free space, 
prepares a message, 
and/or builds an SMF 
record, Type-19 


c 


CVAF 

error 

encountered 


© 


Return to Caller 


3 


To 

IGG032DB 

NONIALL 


Note: “Return to caller" means 
return to the caller of 
the function. 


Figure 12. LSPACE 
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VRF Function 

Description 
The VRF function: 

• Reads VRF data from the the VTOC index map (VIXM). 

• Uses the function code (VRFCODE) in the VRF data to determine the VRF 
recovery routine which is invoked to recover the interrupted function (for 
example, function code X'03' will cause VRF recovery routine, IGGVRF03, 
to be given control). 

• Zeros out VRF data when the updates are completed. 

Note: IGGVRFOO through IGGURF05 are DADSM modules. IGGVRF06 is a 
DFDSS module. See DFDSS: Diagnosis Guide. 

Interface to Controlling Module 

Register 1 contains the UCB address. Register 13 contains the pointer to an 
18-word register save area. The save area must be acquired with the IECRES 
macro. 

System Data Areas Used 
Not applicable 
DADSM Data Areas Used 
Buffer list 
CVAF extent table 
CVAF parameter list 
Data set control blocks (DSCB) 

Transfer control table 
VTOC recording facility data 
WTG table 
Program Organization 
See Figure 13 on page 44. 
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Figure 13. VRF Recovery 
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Module Directory 


The section contains a table that lists each executable object module in DADSM, 
the function and subfunction to which the module belongs, and the figure number 
of the module flowchart in which reference to the object module can be found. 
The figure numbers in boldface indicate where the module is described in detail. 

The majority of DADSM modules reside above 16Mb virtual. The remaining 
modules fall into two categories: modules that always reside below 16Mb virtual, 
IGGPEXIT, IGG19EK, and IGG5S3A, and the installation replaceable modules 
which may or may not reside above 16Mb virtual depending on how they are 
coded. These modules are identified by a footnote in the table below. 


Module 

Function 

Subfunction 

Figure No. (and Part No., 
if applicable) 

IGC0002G 

OBTN 


11 

IGC0002I 1 

SCRTCH 


7-1 

IGC0003B 

ALLOC 

INIT 

2 

IGC00030 1 

RNAME 


10 

IGC0007H 

LSPACE 


12 

IGC0009H 

PRTCT 


9 

IGC0102G 

OBTN 


11 

IGC0107H 

LSPACE 


12 

IGC0109H 

PRTCT 


9 

IGC0209H 

PRTCT 


9 

IGGDAR00 1 

RNAME 


10 

IGGDAR03 

RNAME 


10 

IGGDAS00 1 

SCRTCH 


7-1 

IGGDAS03 

SCRTCH 


7-1 

IGGDATBL 2 

COMMON 




| 1 This module may reside above or below 16Mb virtual. 

| 2 This module is shared by more than one function. 
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Module 

IGGPEXIT 2 

IGGPOSTO 1 2 

IGGPREOO 1 2 

IGGVRFOO 

IGGVRF01 

IGGVRF02 

IGGVRF03 

IGGVRF04 

IGGVRF05 

IGG0CLF2 

IGGQ19EK 2 

IGGQ20D0 

IGG020D1 

IGG020P0 

IGG020P1 

IGG020P2 

IGG020P3 

IGG029AA 

IGG029CM 2 

IGG029DM 1 

IGG029DN 

IGG029DU 1 

IGG029ER 

IGG0290A 

IGG0290B 

IGG0290C 

IGG0290D 

IGG0290E 

IGG0290F 

IGGQ299A 

IGG03QDU 1 

IGG0300F 


Function 


COMMON 


COMMON 


Subfunction 


Figure No. (and Part No., 
if applicable) 
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Module 

Function 

Subfunction 

Figure No. (and Part No., 
if applicable) 

IGG03001 

RNAME 


10,7-1 

IGG03002 

RNAME 


10,7-1 

IGG032DB 

ALLOC 

NONIALL 

3,4-2,6,7-2,8,11,12,13 

IGG032I1 

ALLOC 

IALL 

4-1,2 

IGG032I2 

ALLOC 

IALL 

4-1 

IGG032I3 

ALLOC 

IALL 

4-1 

IGG032I4 

ALLOC 

IALL 

4-1 

IGG032I5 

ALLOC 

IALL 

4-1 

IGG032I6 

ALLOC 

IALL 

4-1 

IGG032I7 

ALLOC 

IALL 

4-2,4-1 

IGG032I8 

ALLOC 

IALL 

4-2 

IGG0325A 

ALLOC 

INIT 

2,5 

IGG0325B 

ALLOC 

NONIALL 

3,2 

IGG0325C 

ALLOC 

NONIALL 

3 

IGG0325D 

ALLOC 

NONIALL 

3 

IGG0325E 

ALLOC 

NONIALL 

3 

IGG0325G 

ALLOC 

NONIALL 

3 

IGG0325H 

ALLOC 

NONIALL 

3,2 

IGG0325I 

ALLOC 

INIT 

2 

IGG0325K 

ALLOC 

NONIALL 

3 

IGG0325P 

ALLOC 

CONV 

5 

IGG0325Q 

ALLOC 

CONV 

5 

IGG0325R 

ALLOC 

CONV 

5 

IGG0325T 

ALLOC 

CONV 

5 

IGG0325U 

ALLOC 

CONV 

5 

IGG0325V 

ALLOC 

CONV 

5 

IGG0325W 

ALLOC 

CONV 

5 

IGG0325Z 

ALLOC 

CONV 

5,2,6 

IGG0553A 

EXTND 


6 

IGG0553B 

EXTND 


6 

IGG0553C 

EXTND 


6 

IGG0553D 

EXTND 


6 
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Module 

Function 

Subfunction 

Figure No. (and Part No., 
if applicable) 

IGG0553E 

EXTND 


6 

IGG0553F 

EXTND 


6,5 

IGG0553G 

EXTND 


6 

IGG05530 

EXTND 


6 
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Data Areas 

System Data Areas 

The following data areas and control blocks used by the DADSM functions can be 
found in Data Areas, available only in microfiche. 

Allocate Work Area 

Mapped by: EECALLWA ifaacro. 

Chained from: Register 13 when the allocate (ALLOC) function is in control. 
Storage Location: Subpool 230. 

Description: Work area used by ALLOC to perform its function. 

Created when: During the allocate initialization subfunction (INIT) by module 
IGC0003B. 

Released when: When the ALLOC function exits, 1GG032SH frees it. 

IGG032I7 frees it if the allocation was an ISAM data set. 

IGG0325I frees it if the allocation was a VIO data set. 

IGG0CLF2 frees it if the allocation was a partitioned data set or a CVOL. 

Extend Work Area 

Mapped by: EECEXTWA macro. 

Chained from: Register 11. 

Storage Location: Subpool 230. 

Description: Used by the extend (EXTND) function to contain control blocks for 
extending the data set. 

I Created when: By module IGG0SS30 during extend initialization (EXTND). 

Released when: By module IGG0SS3E when the EXTND function is finished. 
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Partial Release Work Area 


Scratch Work Area 

i 

Second Scratch Work Area 


Mapped by: IECPRLWA macro. 

Chained from: Register 11 or 13 while the partial release function (PRLSE) is in 
control. 

Storage Location: Subpool 230. 

Description: Used by partial release (PRLSE) to perform its function. 

Created when: The PRLSE function initializes. IGG020P0 creates it for the 
PARTREL caller. IGG020P1 creates it for the close or checkpoint/restart caller. 

Released when: The PRLSE function exits. IGG020P0 frees it for the PARTREL 
caller. IGG020P3 frees it for the close or checkpoint/restart caller. 

Mapped by: IECSCRWA macro. 

Chained from: Register 13 while the scratch function (SCRTCH) is in control. 
Storage Location: Subpool 230. 

Description: Used by scratch (SCRTCH) to perform its function. 

Created when: By module IGGDAS03 during scratch initialization (SCRTCH). 
Released when: By module IGG0290D when SCRTCH finished. 

Mapped by: IECSCRWA macro. 

Chained from: SECWAPTR in IECSCRWA. 

Storage Location: Subpool 230. 

Description: Used by scratch (SCRTCH) to perform its function. 

Created when: During SCRTCH initialization by module IGGDAS03. 

Released when: SCRTCH is finished by module IGG0290D. 


SO MVS/XA DADSM Diagnosis Reference 


LY26-3961-1 © Copyright IBM Corp. 1980,1987 



Restricted Materials of IBM 
Licensed Materials — Property of IBM 


DADSM Data Areas 

The following work areas and control blocks either are used only by the DADSM 
functions, or are mapped within DADSM work areas. 


Buffer List 


Mapped by: ICVAFBFL macro. 

Chained from: Not applicable. 

Storage Location: Within the DADSM function work area and/or built 
dynamically by CVAF in subpool 229. 

Description: The buffer list in the DADSM work area is passed to CVAF through 
the CVAF parameter list in order to read and write VTOC DSCBs; it is supplied to 
the CVAFDIR macro BUFLIST keyword. The buffer lists, built dynamically by 
CVAF, contain the storage locations of the VTOC index space maps and the 
VTOC index entry records (VIERs). All DADSM functions, except ALLOC 
(CONV) and PRTCT, use the buffer list. 

Created when: The buffer list in the DADSM work area is created if DADSM 
needs to call CVAF to read or write a DSCB. The buffer lists built by CVAF are 
created when CVAF is called by DADSM to read the VTOC index space maps 
and/or search the VTOC index entry records. 

Released when: The buffer list in the DADSM work area is released when the 
DADSM work area is released. The buffer lists built by CVAF are released when 
DADSM calls CVAF and specify that the VTOC index entry records and/or the 
VTOC index space maps are to be released. The buffer lists are also released by 
DADSM recovery routines at abnormal termination processing. 


CVAF Extent Table 


Mapped by: ICVARXNT macro. 

Chained from: Not applicable. 

Storage Location: Allocate, extend, scratch, and partial release work areas. 

Description: Used to represent allocated or released space extents when 
interfacing with CVAF. The information contained in the flags field is not used by 
CVAF, differs for each routine, and can be determined by examining the program 
listing. Used by the ALLOC (INIT), EXTND, SCRTCH, PRLSE, and VRF 
functions. 

The used-hole field is not used by CVAF, but is used by DADSM to contain the 
count of the number of format-1, format-2, format-3, format-5, and format-6 
DSCBs added to and removed from the VTOC during allocation or releasing space. 

Each extent entry contains two binary numbers: RTA1 and RTA2. RTA1 is the 
relative track address of the first track of an extent area; RTA2 is the relative track 
address of the last track of the area, plus one. A relative track address is a binary 
number representing the displacement of the track from the first track of the 
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volume. For example, the relative track address of track 7 on cylinder 0 is 7. The 
relative track address of track 3 on cylinder 2 is 23 (if the volume has 10 tracks per 
cylinder). 

Created when: During ALLOC, EXTND, SCRTCH, PRLSE, and VRF function 
processing. 

Released when: Allocate, extend, scratch, partial release, or VRF work areas are 
released. 

CVAF Parameter List 

Mapped by: ICVAFPL macro. 

Chained from: Not applicable. 

Storage Location: Within the DADSM function work area. 

Description: A parameter list supplied to CVAF. All functions, except ALLOC 
(CONV) and PRTCT, use the CVAF parameter list data area. 

Created when: By the DADSM function when CVAF is to be called. 

Released when: By the DADSM function when its work area is released. 

DADSM Extent Table 


Mapped by: ICWLSPC macro. 

Chained from: Not applicable. 

Storage Location: Allocate, extend, scratch, and partial release work areas. 

Description: Used to represent allocated or released space extents when 
interfacing with CVAF. The information contained in the flags field is not used by 
CVAF, differs for each routine, and can be determined by examining the program 
listing. Used by the ALLOC (INIT), EXTND, SCRTCH, PRLSE, and VRF 
functions. 

The used-hole field is not used by CVAF, but is used by DADSM to contain the 
count of the number of format-1, format-2, format-3, format-5, and format-6 
DSCBs added to and removed from the VTOC during allocation or releasing space. 

Each extent entry contains two binary numbers: RTA1 and RTA2. RTA1 is the 
relative track address of the first track of an extent area; RTA2 is the relative track 
address of the last track of the area, plus one. A relative track address is a binary 
number representing the displacement of the track from the first track of the 
volume. For example, the relative track address of track 7 on cylinder 0 is 7. The 
relative track address of track 3 on cylinder 2 is 23 (if the volume has 10 tracks per 
cylinder). 

Created when: During ALLOC, EXTND, SCRTCH, PRLSE, and VRF function 
processing. 
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Released when: Allocate, extend, scratch, partial release, or VRF work areas are 
released. 

DADSM Preprocessing and Postprocessing Installation 

Exit Parameter List 
Mapped by: IECIEXPL macro. 

Chained from: Not applicable. 

Storage Location: Within DADSM function work area. Subpool 230 protect key S. 

Description: The IEXPL contains data supplied to the DADSM preprocessing and 
postprocessing installation exits, IGGPRE00 and IGGPOSTO. It also contains 
fields (IEXFMT1, IEXREASN), which are returned to DADSM allocate from the 
preprocessing exit, as well as a word (IEXRSVWD) which may be used by the 
preprocessing exit for passing data to the postprocessing exit. The DADSM 
functions ALLOC, EXTND, SCRTCH, PRLSE, and RNAME use IEXPL. 

Created when: The DADSM function is to give control to the preprocessing 
installation exit module, IGGPRE00. 

Released when: The DADSM function work area is freed. 


Data Set Control Blocks 


Mapped by: IECSDSL1 macro. 

Chained from: DSCBs reside in the VTOC. Format-1 DSCBs are not chained 
from any record in the VTOC. For an indexed VTOC, the VTOC index entry with 
the data set name of the format-1 DSCB contains the disk address (CCHHR) of 
the format-1 DSCB. Format-2 DSCBs are chained from the format-1 DSCB field, 
DS1PTRDS. Format-3 DSCBs are chained from the format-1 or -2 DSCB fields, 
DS1PTRDS or DS2PTRDS. The format-4 DSCB is the first record in the VTOC; 
the TTR of the format-4 DSCB is in the volume label of the volume and in the 
UCBVTOC field of the UCB. The first format-5 DSCB is the second record in the 
VTOC; subsequent format-5 DSCBs are chained from the previous format-5 
DSCB field, DS5PTRDS. The first format-6 DSCB is chained from the format-4 
DSCB field, DS4F6PTR; subsequent format-6 DSCBs are chained from the 
previous format-6 DSCB field, DS6PTRDS. 

Storage Location: Not applicable. 

Description: A format-1 DSCB describes a data set and the first three extents. A 
format-2 DSCB describes the structure of an ISAM data set. A format-3 DSCB 
describes the 4th through the 16th extent of a data set. Additional format-3 
DSCBs may be used to describe the 17th through the 123rd extent of a VSAM 
data set cataloged in an integrated catalog facility catalog. A format-4 DSCB 
describes the VTOC. A format-5 DSCB describes unallocated space on a volume 
which does not contain a VTOC index. A format-6 DSCB describes the extents 
shared by two or more data sets (split cylinder extents). A format-0 DSCB is an 
unused record in the VTOC. All DADSM functions use the data set control blocks 
(DSCBs). 
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Created when: The format-4 and the first format-5 DSCBs are created when the 
volume is initialized; for a nonindexed VTOC, subsequent format-5 DSCBs are 
created when the number of extents of unallocated space on the volume exceeds 26 
or a multiple of 26; for example, a third format-5 DSCB is created when the 
number of extents goes from 51 to 54 (exceeding 2 x 26). This can occur either 
during allocation or release of space on the volume. The format-1, -2, and perhaps 
format-3 DSCBs are created when the data set is allocated; the format-3 DSCB is 
created when a data set requires a 4th extent. The format-6 DSCB is created when 
the first split cylinder data set on the volume is allocated; subsequent format-6 
DSCBs are created when the number of split extents exceeds 26 or a multiple of 
26. This can happen only when a new split cylinder data set is allocated. 

Allocation of a split-cylinder data set is no longer supported by DADSM, but the 
existing split-cylinder data set can be scratched. A format-0 DSCB is created in all 
DSCBs, except the format-4 and first format-5 DSCB when the volume is 
initialized. A format-0 DSCB is also created when any other DSCB (except the 
first two DSCBs, the format-4 and first format-5 DSCB) is not needed. Format-0, 
-5, and -6 DSCBs are also created by the VTOC convert routine for an OS 
(nonindexed) VTOC. Format-0 DSCBs also are created by the VRF recovery 
routines for an indexed VTOC. 

Released when: A DSCB is released when a format-0 DSCB is written over it. 

The format-4 and first format-5 DSCBs are never released. The format-1 and -2 
DSCBs are released when the data set is deleted. The format-3 DSCB is released 
when the data set is deleted or when the partial release function (PRLSE) reduces 
the number of extents from four or more to three or less. A format-5 DSCB is 
released when the number of extents of unallocated space drops from above a 
multiple of 26 to below or equal to a multiple of 26; for example, the second 
format-5 is released when the number of extents of unallocated space goes from 27 
to 26. This can occur either during allocation or release of volume space on a 
nonindexed VTOC. A format-6 DSCB is released when the number of split 
cylinder extents drops to a multiple of 26 (for example, from 79 to 78); this 
happens only when a split-cylinder data set is deleted. 


Extended Prefix 


Mapped by: IECDSECS macro. 

Chained from: Not applicable. 

Storage Location: The first 80 bytes of the initial work area obtained by the 
DADSNt function. 

Description: Provides a register save area and the addresses of other data areas. 
All DADSM functions, except PRTCT, use the extended prefix. 

Created when: An extended prefix is obtained only with the initial work area 
obtained to process a DADSM request through the IECRES GET macro. 

Released when: The DADSM work area is freed using the IECRES FREE macro. 
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LSPACE Parameter List 

Mapped by: LSPACE macro 

Chained from: Register 1 on entry to IGC0007H. 

Storage location: Caller’s work area. 

Description: A parameter list used by the LSPACE function. 

Created when:: By any caller of LSPACE. 

Released when: Caller’s responsibility. 

LSPACE Work Area 

Mapped by: IECLSPWA macro. 

Chained from: Register 13 while LSPACE is in control. 

Storage Location: Subpool 230. 

Description: Used by the LSPACE function to read DSCBs from the VTOC of 
volumes for which space information is being gathered. 

Created when: During LSPACE initialization by IGC0007H. 

Released when: By LSPACE when LSPACE completes its function. 

Obtain Work Area 

Mapped by: IECOBTWA macro. 

Chained from: Register 13. 

Storage Location: Subpool 230. 

Description: Used by the obtain function (OBTN) to read DSCBs from the 
VTOC. 

Created when: During obtain initialization (OBTN) by IGC0002G, which issues 
the IECRES GET macro. 

Released when: The DADSM work area is freed using the IECRES FREE macro. 
Partial Data Set Control Block 

Mapped by: IECPDSCB macro. 

Chained from: RE ALLOC parameter list. 

Storage Location: Caller’s work area. 

Description: A partial format-1 DSCB (the first 98 bytes) plus the primary space 
request in tracks and the number of directory blocks. 
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Created when: By any authorized caller of allocate (SVC 32, REALLOC). 


PARTREL Parameter list 


Mapped by: PARTREL macro. 

Chained from: Register 1 upon entry to IGG020P0. 

Storage Location: Caller’s work area. 

Description: A parameter list used by the PARTREL partial release (PRLSE) 
function. 

Created when: By any authorized caller of partial release (PARTREL interface). 
Released when: Caller’s responsibility. 

PARTREL Partial Release Work Area 

Mapped by: A concatenation of IECDSECT, DCBD, and IEZDEB macros. 
Chained from: Register 11 or 13. 

Storage Location: Subpool 230. 

Description: A single getmain area which is subdivided to provide module 
IGG020P1 (DADSM partial release prior to PARTREL) a valid execution 
environment. 

Created when: By module IGG020P0 during PARTREL partial release (PRLSE) 
initialization. 

Released when: By Module IGG020P0 when the PRLSE function is finished. 
Password Data Set Record Format 

Chained from: Not applicable. 

Storage Location: The PASSWORD data set. 

Description: The PASSWORD data set contains records with a key length of 52 
bytes and a data length of 80 bytes. The first 44 bytes of the key are the data set 
name, left justified, and padded with blanks. The last 8 bytes of the key are the 
password for the data set. The first two bytes of the data are a binary counter, 
which is incremented when the data set is opened. The third byte of the data is a 
protection mode indicator set to one of four values: 

• X'00' to indicate that the password is a secondary password and the protected 
data set is to be read only 

• X'80' to indicate that the password is the control password and the protected 
data set is to be read only 

• X'01' to indicate that the password is a secondary password and the protected 
data set is to be read and written 
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• X'81 1 to indicate that the password is the control password and the protected 

data set is to be read and written 

Created when: The protect SVC is called to create a new entry in the PASSWORD 
data set. 

Released when: The protect SVC is called to delete the entry in the PASSWORD 
data set. 

Prefix to DADSM Work Areas 

Mapped by: IECDSECS macro. 

Chained from: Prefix to DADSM work area. 

Storage Location: Precedes all work areas obtained by DADSM through the 
IECRES GET macro. 

Description: A prefix, included with each work area, used to chain the work areas 
together. All DADSM functions, except PRTCT, use the prefix to DADSM work 
areas. 

Created when: DADSM work areas are obtained using the IECRES GET macro. 
Released when: The DADSM work area is freed using the IECRES FREE macro. 


Protect Work Area 


Mapped by: EECDSECT macro. 

Chained from: Not chained from or related to the other DADSM work areas. 
Register S points to the protect work area, while protect is in control. 

Storage Location: Subpool 252. 

Description: Used by the PRTCT function to read from and write to the VTOC 
and the PASSWORD data set. 

Created when: During PRTCT initialization by module IGC0009H. 

Released when: By module IGC0209H when the PRTCT function is finished. 


REALLOC Parameter List 


Mapped by: REALLOC macro. 

Chained from: Register 1 upon entry to ALLOCATE (SVC 32) when register l’s 
high order bit is on. 

Storage Location: Caller’s work area. 

Description: A parameter list used by the allocate (ALLOC) function to process a 
partial DSCB that may require more than five extents for the 

Released when: Caller’s responsibility. 
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Recovery Routine Audit Trail 

Mapped by: IECDSECS macro. 

Chained from: Not applicable. 

Storage Location: At the end of the first DADSM work area. 

Description: Used by O/C/EOV-DADSM recovery routines in freeing resources 
allocated to a DADSM routine that has encountered an abnormal termination 
condition. This audit trail tells which resources to free. All DADSM functions, 
except PRTCT, use the audit trail area. 

Created when: Initial DADSM work area is obtained through the IECRES GET 
interface. 

Released when: The DADSM work area is freed. 

Relinquish Parameter List 

Mapped by: ICBAREL macro. 

Chained from: ARHDPTR in Scratch or Partial Release work area. 

Storage Location: Subpool 230. 

Description: A parameter list used by Scratch and Partial Release to pass 
information to MSS on virtual DASD space being released. 

Created when: Scratch or Partial Release determine the volume being processed is 
virtual DASD. 

Released when: Scratch or Partial Release work areas are released. 

Rename Work Area 

Mapped by: IECRENWA macro. 

Chained from: Register 13. 

Storage ^cation: Subpool 230. 

Description: Used by the rename function (RNAME) to read and write DSCBs. 

Created when: During rename initialization (RNAME) by IGGDAR03, which 
issued the IECRES GET macro. 

Released when: When all the volume list entries have been processed. 
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SAF Work Area and Parameter List 

Mapped by: RACROUTE macro. 

Chained from: Not applicable. 

Storage Location: SAF work area and parameter list are processed in the DADSM 
work area. 

Description: The SAF work area is a 512-byte area used by SAF. The SAF 
parameter list is built at the time the RACROUTE macro is issued. It contains 
addresses to the data set name, the volume serial number, the SAF work area, and 
flags. 

Created when: Appears in the DADSM work area. 

Released when: At the completion of the DADSM function. 

Second Rename Work Area 

Mapped by: IECRENWA macro. 

Chained from: SECWAPTR in IECRENWA. 

Storage Location: Subpool 230. 

Description: Used by rename (RNAME) to perform its function. 

Created when: During RNAME initialization by module IGC00030. 

Released when: When all the volume list entries have been processed by RNAME. 

Transfer Control Table 

Mapped by: XCTLTABL macro. 

Chained from: Not applicable. 

Storage Location: Within the module expanding the XCTLTABL macro. 

Description: The transfer control table is a list of module names and their entry 
point addresses (VCONs) that is used to transfer control (using the IECRES 
macro) among the DADSM modules and the close and EOV modules that give 
control to and receive control from the DADSM modules. All DADSM functions, 
except PRTCT, use the transfer control table. 

Created when: Appears at the end of each DADSM module as a result of the 
expansion of the XCTLTABL macro instruction. 

Released when: Not applicable. 
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VTOC Recording Facility (VRF) Data 

Mapped by: IECVRFDA macro. 

Chained from: Not applicable. 

Storage Location: VRF data is processed in the DADSM work area and is 
managed by CVAF in the VTOC index map (VIXM) in the VTOC index. 

Description: VRF data is used by DADSM to record sufficient information about a 
DADSM request to permit any partial updates to the VTOC and VTOC index to 
be either backed out or completed in the event the DADSM function is interrupted. 
The DADSM functions (ALLOC, EXTND, SCRTCH, PRLSE, and RNAME) and 
DFDSS (see DFDSS: Diagnosis Guide ) use the VRF data. Since the VIXM 
contains space for several consecutive copies of VRF data, the VIXM will contain 
a recent history of the last VTOC updates made on the volume. 

Created when: VRF data is created in the DADSM work area as the DADSM 
function begins and before any VTOC or VTOC index updates have occurred. 

The VRF data is moved to the VIXM in virtual storage when DADSM calls the 
CVAF VRF ACCESS=WRITE macro supplying the VRF data. VRF data is 
written to the VTOC index and made active as the first VTOC or VTOC index 
update when DADSM calls the CVAFDIR macro to request that the VIXM 
containing active VRF data be written to the VTOC index. 

Released when: VRF data in the DADSM work area is released when the DADSM 
work area is released. Active VRF data in the VIXM is made inactive when 
DADSM has completed its VTOC updates. The CVAFVRF ACCESS=WRITE 
macro is called by DADSM, supplying no VRF data; this makes the VRF data in 
the VIXM in virtual storage inactive. The last update to the VTOC or VTOC 
index is to write all updated VTOC index entry records and VTOC index space 
maps to the VTOC index, specifying that the VIXM containing no active VRF data 
be the last record written to the VTOC index. 


WTG (Where-to-Go) Table 

Mapped by: Individual DADSM work areas. See description in Appendix A, 
“Data Area Layouts.” 

Chained from: Not applicable. 

Storage Location: Within the primary DADSM function’s work area. 

Description: Used in conjunction with the DECRES LOAD macro instruction to 
transfer control. All DADSM functions, except PRTCT, use the WTG table. 

Created when: DADSM work area acquired. 

Released when: DADSM work area released. 
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Data Area linkages 


To facilitate getting and releasing work areas, the DADSM work areas are chained 
together through the work area prefix (IECPREFX). In most cases, to locate all 
the work areas of a DADSM function, you need only know the contents of the 
register pointing to the work area (usually register 11 or 13) at the time a DADSM 
routine is executing. Register 13 contains the address of the extended prefix of a 
DADSM work area during most DADSM processing. This address is preceded by 
the prefix that contains the address of subsequently obtained work areas associated 
with the DADSM request. Figure 14 on page 62 is an example that shows the 
work area chaining that results from the following conditions: (1) an allocation 
request (SVC 32) is issued, and (2) there is a device that has the RPS feature. 

Figure IS on page 63 shows the linkages on a DASD volume between the VTOC 
and VTOC index. 
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1 Four-character identifiers that appear in the first four bytes of each prefix. The 
DADSM work area identifiers are: 

ALWA Allocate work area 

RPSA RPS work area 

EXWA Extend work area 

LSWA LSPACE work area 

OBWA Obtain work area 

PRWA Partial Release work area 

PRW2 PARTREL Partial Release work area 

REWA Rename work area 

SCWA Scratch work area 

32DB IGG032DB work area 

CVWA IGGVRFOO work area 

CVWB Area containing VRF data for IGGVRFOO 

AVWA IGGVRF01 (Allocate recovery) work area 

EVWA IGGVRF02 (Extend recovery) work area 

SVWA IGGVRF03 (Scratch recovery) work area 

PVWA IGGVRF04 (Partial Release recovery) work area 

RVWA IGGVRF05 (Rename recovery) work area 

figure 14. Example of Data Area Linkage for an Allocation Request 
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(for a nonindexed VTOC only). 


•Can be located anywhere on tha volume 
after cylinder 0, track 0. 

Figure 15. VTOC and VTOC Index linkages 
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Appendix A. Data Area Layouts 


For quick reference, the layout of the VTOC recording facility (VRF) data area is 
given in Figure 16. Any additional layouts of the data areas will be available on 
microfiche. The offsets of the where-to-go (WTG) table are provided in Figure 17 
on page 66. 


Offsets 


Dec. 

(Hex.) 

Length 

Name 

Description 

0 

(0) 

Var. 

VRFDA 

DADSM USE OF VTOC 
RECORDING FACILITY 

0 

(0) 

4 

VRFID 

VRF ID IN EBCDIC 'VRF* 

4 

(4) 

2 

VRFLENG 

LENGTH OF VRF DATA 

6 

(6) 

1 

VRFFCODE 

FUNCTION CODE 

7 

(7) 

1 

VRFFLAG 

VRF FLAG BYTE 



1. 

VRFNEXTD 

EXTEND ON NEW VOLUME 



.1. 

VRFDSNEX 

ON = VRFNDSN EXISTS AT 
OFFSET VRFOFEXT OFF= 
VRFEXTBL EXISTS AT 
OFFSET VRFOFEXT 



..1. 

VRFISAME 

ON = ISAM ALLOCATE 
WITH AN EXISTING FI 
DSCB. OFF= NOT ISAM 
ALLOCATE WITH AN 
EXISTING FI DSCB. 



...i mi 


RESERVED 

8 

(8) 

2 

VRFOFEXT 

OFFSET(nn) TO VRFEXTBL 
OR VRFNDSN IN VRF DATA 

10 

(A) 

1 


RESERVED 

11 

(B) 

1 

VRFPREXT 

NUMBER OF PRIMARY 
EXTENTS 

12 

(C) 

44 

VRFDSN 

DATA SET NAME 

56 

(38) 

5 

VRFF1PTR 

CCHHR OF FI DSCB 

61 

(3D) 

5 

VRFF2PTR 

CCHHR OF F2 DSCB (ISAM 
DS ONLY) 

66 

(42) 

0 

VRFHEND 

END OF VRF DADA 
HEADER 

66 

(42) 

5 

VRFF3PTR 

HEADER CCHHR OF F3 


DSCB(S) 


Figure 16 (Part 1 of 2). VRF Data Area 


LY26-3961-1 © Copyright IBM Corp. 1980,1987 


Appendix A. Data Area Layouts 65 






Restricted Materials of IBM 
Licensed Materials - Property of IBM 


Offsets 

Dec. 

(Hex.) 

Length 

Name 

Description 

71 

(47) 

5 

VRFRSVD 

RESERVED (EXTEND 

71 

(47) 

45 

VRFRSVD 

ONLY) 

UP TO NINE F3 CCHHRs, 

nn 


44 

VRFNDSN 

FOR A TOTAL OF 10 
(ALLOCATE ONLY) 

NEW DATA SET NAME (nn 

nn 


4 

VRFEXTBL 

= VRFOFEXT IN VRF 

DATA) 

DADSM EXTENT TABLE (nn 

nn 

(0) 

1 

VRFEXFLG 

= VRFOFEXT IN VRF 

DATA) 

EXTENT TABLE FLAG 

nn+1 

(1) 

1 

VRFEXCNT 

BYTE 

NUMBER OF ENTRIES (mm) 

nn+2 

(2) 

2 


IN EXTENT TABLE 
RESERVED 

nn+4 

(4) 

Var. 

VRFEXENT 

mm RTA1/RTA2 ENTRIES 


Figure 16 (Part 2 of 2), VRF Data Area 

As shown in the figure below, the where-to-go (WTG) table is always located at 
offsets X^O 1 to X^F 1 in the DADSM work area. It is used by macro IECRES to 
branch into or transfer control to other modules. 


Offsets 





Dec. 

(Hex.) 

Length 

Name 

Description 

112 

(70) 

4 

WTGWTOPR 

WTO 

PREFIX FOR RES WTO 
IECWTGTB POINTS HERE 

116 

(74) 

8 

WTGMODNM 

MODULE NAME 

124 

(7C) 

4 

WTGMODEP 

MODULE ENTRY POINT 
ADDRESS 


Figure 17. DADSM Where-to-Go (WTG) Table Definition 
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Appendix B. DADSM Return Codes 


Allocate Function 

Return 

Code 

0(X'0') 

4 (X’4») 

8(X'8') 
12 (X'C') 


16 

(X'10') 

20 

(X'14') 

24 

(X*18‘) 

28 

(X'lC') 

32 

(X*20') 

36 

(X'24') 

40 

(X'28‘) 

44 

(X*2C') 

48 

(X'30') 

52 

(X'34'> 

56 

(X'38') 


Explanation 
Successful allocation. 

Data set name requested already exists on volume; initial allocation 
not possible under the name given. 

No room available in VTOC or VTOC index. 

One of the following errors was encountered: 

• Permanent I/O error. 

• Error returned by CVAF. 

Requested absolute track not available. 

Requested quantity not available. 

Average record length greater than 6SS3S bytes. 

DSORG or DISP wrong in ISAM index request. 

No prime area request for ISAM data set. 

ISAM prime area must be requested before overflow. 

Space request must begin on cylinder boundary. 

ISAM DSNAME element duplication. 

Invalid REALLOC parameter list. 

Invalid JFCB or partial DSCB pointer. 

Directory space requested is larger than amount available on this 
volume. 
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60 (X'3C') 
64 (X'40') 
68 (X'44*) 
72 (X'48') 
76 (X'4C') 

80 (X'50') 
84 (X'54') 
88 (X'58') 
92 (X'SC’) 
96(X'60') 
100(X'64') 
104 (X'68') 
108 (X'6C') 

112(X*70') 
116 (X'74') 
120(X'78') 

124 (X'7C») 
128 (X'80 1 ) 
132 (X'84‘) 
136 (X'88') 
140 (X'8C') 
144(X'90') 

148(X'94*) 
152(X'98') 
156 (X'9C') 


Restricted Materials of IBM 
licensed Materials — Property of IBM 

Nonindexed VTOC not supported for REALLOC ALLOC=ABS. 
Invalid user label request. 

Invalid UCB pointer. 

DOS VTOC cannot be converted to an OS VTOC. 

No space parameter given for new data set, or zero space requested 
at absolute track zero. 

Invalid request for ISAM index. 

ISAM multivolume index not allowed. 

ISAM DSNAME element invalid. 

ISAM multivolume overflow request not allowed. 

ABSTR AND CYL requests conflict. 

CYL and CONTIG requests conflict. 

Invalid space subparameter. 

Primary space request for an ISAM data set is zero, or primary space 
is zero for an ABSTR request. 

Index area request duplication. 

User labels not supported. 

Invalid combination of values for DSSIZE and minimum allocation 
unit. 

DSSIZE is not a multiple of the minimum allocation unit. 

Directory space request is larger than primary request. 

Space request must be ABSTR for DOS volume. 

Invalid F3 DSCB pointer. 

ISAM index must be requested before prime area. 

Last concatenated DD card unnecessary or invalid for this ISAM 
data set. 

Overlapping extents in VTOC. 

Overlapping DOS split cylinder extents in VTOC. 

DADSM allocation terminated because of possible VTOC error. 
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160 (X'AO') ISAM allocation terminated because of possible VTOC error. 

164 (X'A4') Allocation terminated because of DOS stacked pack format. 

168 (X'A8') RACF define faded; data set profile already defined. 

172 (X'AC') User not authorized to define data set. 

176 (X'BO 1 ) Installation exit rejected the request with a return code of 8; no 
further volume should be attempted. 

180(X'B4') Installation exit rejected the request with a return code of 4. Fora 
nonspecific volume request; another volume may be attempted. 

184 (X'B8'> RACF define with modeling specified and model not found. 

188 (X'BC*) Invalid F2 DSCB pointer. 

Extend Function 

ToEOV 

Return 

Code Explanation 

1 (X* 1') Successful secondary allocation on the current volume. 

4 (X'4'> Successful secondary allocation on the new volume. 

-1 (X'-l') Error in secondary allocation on the current volume. 

— Fewer than three free VTOC records (format-0 DSCBs) 

— Quantity not available 

— Too many extents (more than 16) for the data set on this 
volume 
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Return 

Code Explanation 

-4 (X'-4') Error in secondary allocation on the new volume. 

— Duplicate name on the new volume 
— Fewer than three free VTOC records (format-0 DSCBs) 

— Quantity not available 

-8 (X'-8') Unable to convert VTOC to standard format, or a volume with the 
alternate tracks on cylinder 0 was encountered (DOS allocation). 

-12 (X'-C') Unable to define the new volume to RACF. 

-18 (X'-10') Permanent I/O error or unexpected CVAF error return code. 

-20 (X'-14') Installation rejected the request. 

To Integrated Catalog Facility/VSAM Catalog Management 

Return 

Code Explanation 

161(X'A1') Return code for integrated catalog facility catalog caller. Successful 
secondary allocation on the current volume. 

129(X'81') Return code for VSAM catalog caller. Successful secondary 
allocation on the current volume. 

-8 (X'-8') Unable to convert the VTOC to standard format. 

-16 (X'-10') Permanent I/O error or unexpected CVAF error return code. 

-20 (X'-14'> Installation exit rejected the request. 

-129 (X'-81') Return code for VSAM catalog caller. Error in secondary allocation 
on the new volume. 

— Fewer than three free VTOC records (format-0 DSCBs) 

— Quantity not available 

— Too many extents for the data space on this volume 

-161 (X'-Al') Return code for integrated catalog facility catalog caller. The 
reason is the same as that documented in -129 above. 
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To OS Catalog Management 

Return 

Code Explanation 

2 (X'2'> Successful secondary allocation on the current volume. 

-2 (X' -2 1 ) Error in secondary allocation on the current volume. 

- Fewer than three free VTOC records (format-0 DSCBs) 

- Quantity not available 

- Too many extents (more than 16) for the data set on this 
volume 

-8 (X'-8') Unable to convert VTOC to standard format, or a volume with the 
alternate tracks on cylinder 0 was encountered (DOS allocation). 

-16 (X'-10') Permanent I/O error or unexpected CVAF error return code. 

-20 (X'-14') Installation rejected the request. 


LSPACE Function 

Return 

Code Explanation 

0 (X'O') Successful LSPACE processing. 

4 (X'4') I/O error while reading DSCBs or unexpected CVAF error return 
code. 

8 (X'8 1 ) Last allocation on this volume made under DOS, or a DADSM 

function has prematurely terminated and VTOC errors may exist. 

12 (X'O) UCB address invalid. UCB not for direct access device. UCB 
not-ready bit is on, indicating device not ready; UCBVTOC=0, 
indicating volume not mounted. 

If a message area was specified, the reason associated with the return 
code is stored there. 

16 (X' 10') Invalid message area address or SMF indicator. 

| Figure 18 shows additional diagnostic information returned by LSPACE. This 

| information is returned in Register 0, and, if the return code is not 16, in the 

| LSPACE parameter list as well. 
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1 

1 

LSPAERCD 

LSPASFID 

LSPASFRT 

LSPASFRS 

Description 


16 (10) 

X'01* 

N/A 

X'01' 

Bad parm list storage key 


16 (10) 

X'01' 

N/A 

X'02' 

Bad parm list ID 


12 (0C) 

X'01' 

N/A 

X'03' 

Invalid LSPACE flag 


12 (0C) 

X'01' 

N/A 

X'04' 

Not authorized for SMF 


12 (0C) 

X'01' 

N/A 

X'05' 

Bad MSG/DATA area storage key 


12 (0C) 

X'01' 

N/A 

X'06* 

Bad FMT4 Area storage key 


12 (0C) 

X'01' 

N/A 

X'07' 

UCB not found 


12 (0C) 

X'01' 

N/A 

X'08* 

UCB not direct access device 


12 (0C) 

X'01' 

N/A 

X'09‘ 

UCB VTOC pointer is zero 


12 (0C) 

X'02' 

N/A 

N/A 

Invalid UCB status 


12 (OC) 

X'03' 

ENQ RETC 

N/A 

Failed ENQ on SYSZDMNT 


08 (08) 

X'04' 

N/A 

N/A 

F5’s are invalid 


04(04) 

X'04' 

ECB STAT 

N/A 

Error reading F4 & F5 


04(04) 

X'05' 

ECB STAT 

N/A 

Error reading next FS 


04(04) 

X’06' 

ECB STAT 

N/A 

Error reading volume label 


04(04) 

X'80' 

DIR RETC 

CVSTAT 

Error getting F4/Space maps 


04(04) 

X'81' 

DSM RETC 

CVSTAT 

Error getting free extents 


04(04) 

X'82‘ 

DSM RETC 

CVSTAT 

Error getting F0 count 


04(04) 

X'83' 

DSM RETC 

CVSTAT 

Error getting VIR count 


04 (04) 

X'84' 

VRFRETC 

CVSTAT 

Error checking for VRF 

1 

00(00) 

X'00» 

N/A 

N/A 

No problems 


Figure IS. DADSM LSPACE Diagnostic Information 



Abbreviation 

Meaning 


LSPAERCD 

Return code 


LSPASFID 

Subfunction identifier 


LSPASFRT 

Subfunction return code 


LSPASFRS 

Subfunction reason code 


N/A 

Not Applicable 


CVSTAT 

CVSTAT field of CVAF parameter list 


ENQ RETC 

Return code from ENQ 


DIR RETC 

Return code from CVAFDIR 


DSM RETC 

Return code from CVAFDSM 


VRFRETC 

Return code from CVAF VRF 


ECB STAT 

ECB completion code 
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Obtain Function 

Return 

Code 

0(X'0') 

4 (X'4*) 

8(X’8') 

12 (X'C) 

16 (X'10') 
20 ('14') 

Partial Release Function 

Return 

Code 

0 (X'O*) 

2 (X'2‘) 

4 (X'4') 

8 (X'8') 

12 (X'C') 

16 (X'10 1 ) 

20(X'14») 
24 (X'18') 
28 (X'lC') 
32(X'20') 


Explanation 

Successful completion of Obtain routine. 

The required volume was not mounted. 

The FI DSCB was not found in the VTOC of the specified volume. 

A permanent I/O error or an invalid FI or F4 DSCB was 
encountered when processing the specified volume or an unexpected 
CVAF error return code was encountered. 

The pointer to the work area passed by the caller was invalid. 

The absolute address passed (seek option) was not with the 
boundaries of the VTOC. 


Explanation 

The requested partial release was successful. 

Unable to find extent in FI DSCB. 

Unable to find extent in F3 DSCB. 

Another DCB is open to the data set. 

Invalid parameter list. 

A permanent I/O error was encountered during processing, or an 
unexpected CVAF error return code was encountered, or the 
installation exit rejected the request, or an I/O error occurred while 
tracks to be released were being erased. 

DSN, or DSN pointer is invalid. 

Invalid UCB pointer. 

Given DSORG is not supported. 

No space in VTOC. 
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Protect Fraction 


Return 

Code 

O(X'O') 

4(X*4') 

8 (X'8') 

I2(X'C') 
16(X'10') 
20 (X'14 1 ) 
24 (X'18 1 ) 1 
28 (X'lC') 
32 (X'20') 2 

36 (X’24») 2 
40 (X'28') 2 
44 (X'2C') 
48 (X'30 1 ) 2 
52 (X'34 1 ) 2 
56 (X’38') 2 


Explanation 

The PASSWORD data set was successfully updated. 

The password of the data set name was already in the PASSWORD 
data set. 

The password of the data set name was not in the PASSWORD data 
set. 

A control password is required or the one supplied is incorrect. 

The supplied parameter list was incomplete or incorrect. 

There was an I/O error in the password data set. 

The PASSWORD data set was full. 

The validity check of the buffer address failed. 

The LOCATE macro failed. LOCATE’s return code is in register 1 
and the number of indexes searched is in register 0. 

The OBTAIN macro failed. OBTAIN’s return code is in register 1. 

The DSCB could not be updated. 

The PASSWORD data set does not exist. 

Tape data set cannot be protected. 

Data set in use. 

The data set uses the virtual storage access method (VSAM). 


Notes: 

1 For this return code, a message is written to the console, indicating that the 
PASSWORD data set is full. 

2 For these return codes, the PASSWORD data set has been updated, but the 
DSCB has not been flagged to indicate the protected status of the data set. 
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Rename Function 

Return 

Code Explanation 

0 (X'O 1 ) Successful completion. 

4 (X'4 1 ) No volumes containing any part of the data set were mounted, nor 
did register 0 contain the address of a unit that was available for 
mounting a volume of the data set to be renamed (this completion 
code is accompanied by a setting of 5 in the rename status code of 
each entry of the volume list). 

8 (X'8'> An unusual condition was encountered on one or more of the 
volumes. 

12 (X'C*) The volume list passed to rename was not valid (this return code is 
not accompanied by the setting of a rename status code in the 
volume list). 

After the RENAME macro instruction is executed, the last byte of each 12-byte 
entry in the volume list indicates the following conditions: 

RENAME 

Status 

Code Explanation 

0 (X’O') The FI DSCB for the data set has been renamed in the VTOC on 
this volume. 

1 (X* 1') The VTOC of this volume does not contain the FI DSCB of the data 

set to be renamed. 

2 (X'2') The data set could not be renamed because the data set was 

password protected and the password was not supplied in the two 
attempts allowed, or an attempt was made to rename a VSAM data 
space, or an attempt was made to rename a VTOC index data set. 

3 (X'3') An FI DSCB containing the new data set name already exists in the 

VTOC of this volume, or an attempt was made to rename a data set 
to a name starting with 'SYSl.VTOCDCV 

4 (X'4 1 ) A permanent I/O error or an invalid FI DSCB was encountered 

while trying to rename the data set on this volume, or there is no 
space in the index VIER for the new name, and no additional VIERs 
are available. 

5 (X'S') It could not be verified that this volume was mounted nor was there a 

unit available for mounting the volume. 

6 (X'6') The operator was unable to mount this volume. If the volume is an 

MSS virtual volume and is running in a JES3 environment, JES3 
would not allow the volume to be mounted. 
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7 (X'7') The data set was not renamed because it was currently open for 

processing. 

8 (X'8') The data set is defined to RACF, but either the accessor is not alter 

authorized to the data set or the data set is defined to RACF on 
multiple volumes. 


Scratch Function 

Return 

Code Explanation 

0(X'0') Successful scratch 

4 (X'4*) No volumes containing any part of the data set were mounted, nor 
did register 0 contain the address of a unit that was available for 
mounting a volume of the data set to be scratched. (This return code 
is accompanied by the setting of status code 5 in all entries of the 
volume list.) 

8 (X'8’) An unusual condition was encountered on one or more volumes This 
return code is not accompanied by the setting of a status code. 

| 12 (X'C') Issued for one of the following reasons: 

| • Invalid parameter list address. 

| • Invalid volume list address. 

| • Invalid volume count. 

j • Conflicting options (both ERASE and NOERASE) were found 

I in the parameter list. 

After the SCRATCH macro instruction is executed, the last byte of each 12-byte 
entry in the volume list indicates the following conditions: 

Scratch 

Status 

Code Explanation 

0 (X'O') The DSCB for the data set has been deleted from the VTOC on the 
volume pointed to. 

1 (X* 1') The VTOC of this volume does not contain the DSCB to be deleted. 

2 (X'2 1 ) The macro instruction failed when the correct password was not 

supplied by the console operator or TSO terminal operator in the two 
attempts allowed, or the user tried to scratch a VSAM data space or 
a VTOC index data set. 

3 (X’3') The DSCB was not deleted because either the OVRD option was not 

specified or the retention cycle had not expired. 
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Scratch 

Status 

Code 

4 (X'4‘) 


5 (X'5') 

6(X'6') 

7 (X'7') 
8(X*8') 


Explanation 

A permanent I/O error on an invalid FI DSCB was encountered 
when processing this volume; or an unexpected CVAF error return 
code was encountered; or the installation exit rejected the request; or 
an I/O error occurred while the DASD tracks occupied by the data 
set were being erased when the ERASE option was specified in the 
scratch parameter list or when the ERASE attribute was specified for 
a RACF-defined data set. 

It could not be verified that this volume was mounted, nor was there 
a unit available for mounting the volume. If one or more of the 
volumes was an MSS mass-storage volume, see the explanation of 
message IEC666I in System Messages. 

The operator was unable to mount this volume. If this volume is an 
MSS virtual volume and is running in a JES3 environment, JES3 
would not allow the volume to be mounted. 

The DSCB was not deleted because the data set was open. 

The DSCB indicates the data set is defined to RACF but either the 
accessor is not authorized to the data set or to the volume, or the 
data set is a VSAM data space. 
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List of Abbreviations 


BPAM 

Basic Partitioned Access Method 

RACF 

Resource Access Control Facility 

CVAF 

Common VTOC Access Facility 

RBA 

Relative byte address 

CVPL 

CVAF parameter list 

R/TM 

Recovery termination manager 

DADSM 

Direct Access Device Space 
Management 

SAF 

System Authorization Facility 



SMF 

System management facilities 

DCB 

Data control block 

SVC 

Supervisor call instruction 

DEB 

Data extent block 

SVRB 

Supervisor request block 

DFDSS 

Data Facility Data Set Services 

TTR 

Track, track record 

DIRF 

DADSM interrupt-recording 
facility 

UCB 

Unit control block 

DOS 

Disk Operating System 

VDSCB 

Virtual data set control block 

DSAB 

Data set association block 

VIER 

VTOC index entry record 

DSCB 

Data set control block 

VIO 

Virtual I/O 

EOV 

End of volume 

VIXM 

VTOC index map 

GTF 

Generalized Trace Facility 

VMDS 

VTOC map of DSCBs 

ICKDSF 

Device Support Facility 

VPSM 

Volume pack space map 

ISAM 

Indexed Sequential Access Method 

VRF 

VTOC recording facility 

JFCB 

Job file control block 

VSAM 

Virtual Storage Access Method 

MSS 

Mass storage system 

VTOC 

Volume table of contents 

PDSCB 

Partial data set control block 

WTG 

Where-to-go 
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